<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python documentation Index' />
<link rel="first" href="lib.html" title='Python library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="addresslist-objects.html" />
<link rel="prev" href="module-rfc822.html" />
<link rel="parent" href="module-rfc822.html" />
<link rel="next" href="addresslist-objects.html" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name='aesop' content='information' />
<title>7.10.1 Message Objects </title>
</head>
<body>
<div class="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="7.10 rfc822  "
  href="module-rfc822.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="7.10 rfc822  "
  href="module-rfc822.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="7.10.2 addresslist Objects"
  href="addresslist-objects.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-rfc822.html">7.10 rfc822  </a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-rfc822.html">7.10 rfc822  </a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="addresslist-objects.html">7.10.2 AddressList Objects</a>
</div>
<hr /></div>
</div>
<!--End of Navigation Panel-->

<h2><a name="SECTION0091010000000000000000"></a><a name="message-objects"></a>
<br>
7.10.1 Message Objects 
</h2>

<p>
A <tt class="class">Message</tt> instance has the following methods:

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1571' xml:id='l2h-1571' class="method">rewindbody</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Seek to the start of the message body.  This only works if the file
object is seekable.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1572' xml:id='l2h-1572' class="method">isheader</tt></b>(</nobr></td>
  <td><var>line</var>)</td></tr></table></dt>
<dd>
Returns a line's canonicalized fieldname (the dictionary key that will
be used to index it) if the line is a legal <a class="rfc" id='rfcref-99758' xml:id='rfcref-99758'
href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a> header; otherwise
returns <code>None</code> (implying that parsing should stop here and the
line be pushed back on the input stream).  It is sometimes useful to
override this method in a subclass.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1573' xml:id='l2h-1573' class="method">islast</tt></b>(</nobr></td>
  <td><var>line</var>)</td></tr></table></dt>
<dd>
Return true if the given line is a delimiter on which Message should
stop.  The delimiter line is consumed, and the file object's read
location positioned immediately after it.  By default this method just
checks that the line is blank, but you can override it in a subclass.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1574' xml:id='l2h-1574' class="method">iscomment</tt></b>(</nobr></td>
  <td><var>line</var>)</td></tr></table></dt>
<dd>
Return <code>True</code> if the given line should be ignored entirely, just skipped.
By default this is a stub that always returns <code>False</code>, but you can
override it in a subclass.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1575' xml:id='l2h-1575' class="method">getallmatchingheaders</tt></b>(</nobr></td>
  <td><var>name</var>)</td></tr></table></dt>
<dd>
Return a list of lines consisting of all headers matching
<var>name</var>, if any.  Each physical line, whether it is a continuation
line or not, is a separate list item.  Return the empty list if no
header matches <var>name</var>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1576' xml:id='l2h-1576' class="method">getfirstmatchingheader</tt></b>(</nobr></td>
  <td><var>name</var>)</td></tr></table></dt>
<dd>
Return a list of lines comprising the first header matching
<var>name</var>, and its continuation line(s), if any.  Return
<code>None</code> if there is no header matching <var>name</var>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1577' xml:id='l2h-1577' class="method">getrawheader</tt></b>(</nobr></td>
  <td><var>name</var>)</td></tr></table></dt>
<dd>
Return a single string consisting of the text after the colon in the
first header matching <var>name</var>.  This includes leading whitespace,
the trailing linefeed, and internal linefeeds and whitespace if there
any continuation line(s) were present.  Return <code>None</code> if there is
no header matching <var>name</var>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1578' xml:id='l2h-1578' class="method">getheader</tt></b>(</nobr></td>
  <td><var>name</var><big>[</big><var>, default</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Like <code>getrawheader(<var>name</var>)</code>, but strip leading and trailing
whitespace.  Internal whitespace is not stripped.  The optional
<var>default</var> argument can be used to specify a different default to
be returned when there is no header matching <var>name</var>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1579' xml:id='l2h-1579' class="method">get</tt></b>(</nobr></td>
  <td><var>name</var><big>[</big><var>, default</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
An alias for <tt class="method">getheader()</tt>, to make the interface more compatible 
with regular dictionaries.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1580' xml:id='l2h-1580' class="method">getaddr</tt></b>(</nobr></td>
  <td><var>name</var>)</td></tr></table></dt>
<dd>
Return a pair <code>(<var>full name</var>, <var>email address</var>)</code> parsed
from the string returned by <code>getheader(<var>name</var>)</code>.  If no
header matching <var>name</var> exists, return <code>(None, None)</code>;
otherwise both the full name and the address are (possibly empty)
strings.

<p>
Example: If <var>m</var>'s first <span class="mailheader">From:</span> header contains the
string <code>'jack@cwi.nl (Jack Jansen)'</code>, then
<code>m.getaddr('From')</code> will yield the pair
<code>('Jack Jansen', 'jack@cwi.nl')</code>.
If the header contained
<code>'Jack Jansen &lt;jack@cwi.nl&gt;'</code> instead, it would yield the
exact same result.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1581' xml:id='l2h-1581' class="method">getaddrlist</tt></b>(</nobr></td>
  <td><var>name</var>)</td></tr></table></dt>
<dd>
This is similar to <code>getaddr(<var>list</var>)</code>, but parses a header
containing a list of email addresses (e.g. a <span class="mailheader">To:</span> header) and
returns a list of <code>(<var>full name</var>, <var>email address</var>)</code> pairs
(even if there was only one address in the header).  If there is no
header matching <var>name</var>, return an empty list.

<p>
If multiple headers exist that match the named header (e.g. if there
are several <span class="mailheader">Cc:</span> headers), all are parsed for addresses.
Any continuation lines the named headers contain are also parsed.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1582' xml:id='l2h-1582' class="method">getdate</tt></b>(</nobr></td>
  <td><var>name</var>)</td></tr></table></dt>
<dd>
Retrieve a header using <tt class="method">getheader()</tt> and parse it into a 9-tuple
compatible with <tt class="function">time.mktime()</tt>; note that fields 6, 7, and 8 
are not usable.  If there is no header matching
<var>name</var>, or it is unparsable, return <code>None</code>.

<p>
Date parsing appears to be a black art, and not all mailers adhere to
the standard.  While it has been tested and found correct on a large
collection of email from many sources, it is still possible that this
function may occasionally yield an incorrect result.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1583' xml:id='l2h-1583' class="method">getdate_tz</tt></b>(</nobr></td>
  <td><var>name</var>)</td></tr></table></dt>
<dd>
Retrieve a header using <tt class="method">getheader()</tt> and parse it into a
10-tuple; the first 9 elements will make a tuple compatible with
<tt class="function">time.mktime()</tt>, and the 10th is a number giving the offset
of the date's timezone from UTC.  Note that fields 6, 7, and 8 
are not usable.  Similarly to <tt class="method">getdate()</tt>, if
there is no header matching <var>name</var>, or it is unparsable, return
<code>None</code>. 
</dl>

<p>
<tt class="class">Message</tt> instances also support a limited mapping interface.
In particular: <code><var>m</var>[name]</code> is like
<code><var>m</var>.getheader(name)</code> but raises <tt class="exception">KeyError</tt> if
there is no matching header; and <code>len(<var>m</var>)</code>,
<code><var>m</var>.get(<var>name</var><big>[</big>, <var>default</var><big>]</big>)</code>,
<code><var>m</var>.has_key(<var>name</var>)</code>, <code><var>m</var>.keys()</code>,
<code><var>m</var>.values()</code> <code><var>m</var>.items()</code>, and
<code><var>m</var>.setdefault(<var>name</var><big>[</big>, <var>default</var><big>]</big>)</code> act as
expected, with the one difference that <tt class="method">setdefault()</tt> uses
an empty string as the default value.  <tt class="class">Message</tt> instances
also support the mapping writable interface <code><var>m</var>[name] =
value</code> and <code>del <var>m</var>[name]</code>.  <tt class="class">Message</tt> objects do not
support the <tt class="method">clear()</tt>, <tt class="method">copy()</tt>, <tt class="method">popitem()</tt>, or
<tt class="method">update()</tt> methods of the mapping interface.  (Support for
<tt class="method">get()</tt> and <tt class="method">setdefault()</tt> was only added in Python
2.2.)

<p>
Finally, <tt class="class">Message</tt> instances have some public instance variables:

<p>
<dl><dt><b><tt id='l2h-1584' xml:id='l2h-1584' class="member">headers</tt></b></dt>
<dd>
A list containing the entire set of header lines, in the order in
which they were read (except that setitem calls may disturb this
order). Each line contains a trailing newline.  The
blank line terminating the headers is not contained in the list.
</dl>

<p>
<dl><dt><b><tt id='l2h-1585' xml:id='l2h-1585' class="member">fp</tt></b></dt>
<dd>
The file or file-like object passed at instantiation time.  This can
be used to read the message content.
</dl>

<p>
<dl><dt><b><tt id='l2h-1586' xml:id='l2h-1586' class="member">unixfrom</tt></b></dt>
<dd>
The <span class="Unix">Unix</span> "<tt class="samp">From&nbsp;</tt>" line, if the message had one, or an empty
string.  This is needed to regenerate the message in some contexts,
such as an <code>mbox</code>-style mailbox file.
</dl>

<p>

<div class="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="7.10 rfc822  "
  href="module-rfc822.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="7.10 rfc822  "
  href="module-rfc822.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="7.10.2 addresslist Objects"
  href="addresslist-objects.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-rfc822.html">7.10 rfc822  </a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-rfc822.html">7.10 rfc822  </a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="addresslist-objects.html">7.10.2 AddressList Objects</a>
</div>
</div>
<hr />
<span class="release-info">Release 2.5.1, documentation updated on 18th April, 2007.</span>
</div>
<!--End of Navigation Panel-->
<address>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</address>
</body>
</html>
